Provides an array version of the TextWidth function. For each character in the specified text, MeasureText calculates the width of the character’s glyph in pixels from the left edge of the text segment.

void MeasureText (
    SInt16 count, 
    const void *textAddr, 
    void *charLocs
);

Parameter descriptions

count

The number of bytes (as opposed to characters) to be measured. Because 2-byte script systems also include characters consisting of only one byte, do not simply multiply the number of characters by 2 to determine this value; you must determine and specify the correct number of bytes.

For 2-byte characters, the charLocs array contains two entries—one corresponding to each byte—but both entries contain the same pixel-width value.

textAddr

A pointer to the memory location of the beginning of the text to be measured. The value of textAddr must point directly to the first character whose glyph is to be measured.

charLocs

A pointer to an application-defined array of count + 1 integers. On return, the first element in the charLocs array contains 0 and the last element contains the total width of the text segment, when the primary line direction is left to right and the text is unidirectional.

When the primary line direction is right to left, and the text is unidirectional, the first element in the array contains the total width of the text segment, and the last element in the array contains 0. When the text is bidirectional, at a direction boundary, MeasureText selects the character whose direction maps to that of the primary line direction.

DISCUSSION

The MeasureText function calculates the onscreen pixel width of the glyph of each character, beginning from the left edge of the text segment. The function returns the same results that an application would get if it called CharToPixel for each character with a direction parameter value of hilite. Using MeasureText to find the pixel location of a character’s glyph is less efficient than using the CharToPixel function because the application must define the array pointed to by charLocs, and then walk the array after MeasureText returns the results.

Because this function measures text in the font, style, and size of the current graphics port, you need to call it once for each individual style run in any line of text that contains multiple style runs.

For more information about MeasureText, contact Developer Technical Support.

Some fonts in 1-byte script systems may have zero-width characters, which are usually overlapping diacritical marks that typically follow the base character in memory. In this case, MeasureText measures both the glyph of the base character (the high-order, low-address byte) and the width of the diacritical mark. The charLoc array includes an entry for each, but both entries contain the same value.

For 1-byte complex script systems, MeasureText calculates the widths of any ligatures, reversals, compound characters, and character clusters that need to be drawn. For example, for an Arabic ligature, the entry that corresponds to the trailing edge of each character that is part of the ligature is the trailing edge of the entire ligature.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)